home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / Translation.idl < prev    next >
Encoding:
Text File  |  1996-05-01  |  8.8 KB  |  227 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Translation.idl
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __TRANSLATION_IDL__
  19. #define __TRANSLATION_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27. #ifndef __FILES_IDL__
  28. #include <Files.idl>
  29. #endif
  30. #ifndef __COMPONENTS_IDL__
  31. #include <Components.idl>
  32. #endif
  33. #ifndef __TRANSLATIONEXTENSIONS_IDL__
  34. #include <TranslationExtensions.idl>
  35. #endif
  36.  
  37. #ifdef __SOMIDL__
  38.  
  39. /* enumerated types on how a document can be opened*/
  40. typedef short                    DocOpenMethod;
  41.  
  42. /* 0L terminated array of OSTypes, or FileTypes*/
  43. typedef OpaquePtr                TypesBlock;                    /* Substituted OpaquePtr for array of OSType of size 64 */
  44.  
  45. typedef OpaquePtr                TypesBlockPtr;                /* Substituted OpaquePtr for “OSType*” */
  46.  
  47. /* Progress dialog resource ID*/
  48. /* block of data that describes how to translate*/
  49. typedef SOMLargeStruct            FileTranslationSpec;        /* Derived from a struct of 48 bytes in size */
  50.  
  51. typedef OpaquePtr                FileTranslationSpecArrayPtr; /* Substituted OpaquePtr for “FileTranslationSpec*” */
  52.  
  53. #if FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE
  54. /*
  55. ****************************************************************************************
  56. * 
  57. *   GetFileTypesThatAppCanNativelyOpen
  58. * 
  59. *  This routine returns a list of all FileTypes that an application can open by itself
  60. * 
  61. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  62. *             appSignature        signature (creator) of application
  63. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  64. * 
  65. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  66. */
  67. /*
  68. ****************************************************************************************
  69. * 
  70. *  ExtendFileTypeList
  71. * 
  72. *  This routine makes a new list of file types that can be translated into a type in the given list
  73. *  Used by StandardFile
  74. * 
  75. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  76. *             numberOriginalTypes        number of file types in orgTypeList
  77. *              extendedTypeList        pointer to a buffer to be filled with file types
  78. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  79. * 
  80. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  81. *             numberExtendedTypes        number of file types put in extendedTypeList
  82. */
  83. /*
  84. ****************************************************************************************
  85. * 
  86. * 
  87. *  This routine checks if a file can be opened by a particular application.
  88. *  If so, it returns if it needs to be translated first, and if so then how.
  89. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  90. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  91. * 
  92. *  Enter:    targetDocument        document to check if it can be opened
  93. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  94. *             appSignature        signature (creator) of application to open doc
  95. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  96. *             onlyNative            whether to consider if document can be translated before opening
  97. *             howToOpen            pointer to buffer in which to put how the document can be opened
  98. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  99. * 
  100. *  Exit:    howToOpen            whether file needs to be translated to be read
  101. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  102. *             returns                noErr, noPrefAppErr
  103. */
  104. /*
  105. ****************************************************************************************
  106. * 
  107. *  GetFileTranslationPaths
  108. * 
  109. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  110. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  111. * 
  112. *  Enter:    srcDoc            source file or NULL for all matches
  113. *             dstDoc            destination FileType or NULL for all matches
  114. *             maxResultCount
  115. *             resultBuffer
  116. *  Exit:    number of paths
  117. */
  118. /*
  119. ****************************************************************************************
  120. * 
  121. *  GetPathFromTranslationDialog
  122. * 
  123. *  This routine, with a given document, application, and a passed typelist will display the
  124. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  125. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  126. *  The routine returns the translation path information.
  127. * 
  128. *  Enter:    theDocument            FSSpec to document to open
  129. *             theApplication        FSSpec to application to open document
  130. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  131. *                                 you would like the documented translated to.  Order most perferred
  132. *                                 to least.
  133. * 
  134. *  Exit:    howToOpen            Translation method needed to open document
  135. *             howToTranslate        Translation specification
  136. *             returns                Any errors that might occur.
  137. */
  138. /*
  139. ****************************************************************************************
  140. * 
  141. *   TranslateFile
  142. * 
  143. *  This routine reads a file of one format and writes it to another file in another format. 
  144. *  The information on how to translated is generated by the routine CanDocBeOpened.
  145. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  146. *  The destination file must not exist.  It is created by this routine.  
  147. * 
  148. *  Enter:    sourceDocument            input file to translate
  149. *             destinationDocument        output file of translation
  150. *             howToTranslate            pointer to info on how to translate
  151. *  Exit:    returns                    noErr, badTranslationSpecErr 
  152. */
  153. /*
  154. ****************************************************************************************
  155. * 
  156. *   GetDocumentKindString
  157. * 
  158. *  This routine returns the string the Finder should show for the "kind" of a document
  159. *  in the GetInfo window and in the kind column of a list view.  
  160. * 
  161. *  Enter:    docVRefNum        The volume containing the document
  162. *             docType            The catInfo.fdType of the document
  163. *             docCreator        The catInfo.fdCreator of the document
  164. *             kindString        pointer to where to return the string
  165. * 
  166. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  167. *             returns            noErr, or afpItemNoFound if kind could not be determined
  168. */
  169. /*
  170. ****************************************************************************************
  171. * 
  172. *  GetTranslationExtensionName
  173. * 
  174. *  This routine returns the translation system name from a specified TranslationSpec
  175. * 
  176. *  Enter:    translationMethod    The translation path to get the translation name from
  177. * 
  178. *  Exit:    extensionName        The name of the translation system
  179. *             returns                Any errors that might occur
  180. */
  181. /*
  182. ****************************************************************************************
  183. * 
  184. *  GetScrapDataProcPtr
  185. * 
  186. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  187. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  188. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  189. *  with a list all the formats that you have available to be translated, and the length of each.
  190. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  191. *  the formats that 'fmts' list said was available.
  192. * 
  193. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  194. *             dataH                    Handle in which to put the requested data
  195. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  196. *             
  197. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  198. */
  199. typedef OpaquePtr GetScrapDataProcPtr;
  200. typedef OpaquePtr GetScrapDataUPP;
  201. typedef GetScrapDataUPP            GetScrapData;
  202.  
  203. /*
  204. ****************************************************************************************
  205. * 
  206. *  TranslateScrap
  207. * 
  208. *  This routine resizes the destination handle and fills it with data of the requested format.
  209. *  The data is generated by translated one or more source formats of data supplied by
  210. *  the procedure srcDataGetter.  
  211. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  212. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  213. * 
  214. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  215. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  216. *             destinationFormat            Format of data desired
  217. *             destinationData                Handle in which to store translated data
  218. *             
  219. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  220. */
  221. #endif
  222.  
  223. #endif /* __SOMIDL__ */
  224.  
  225. #endif /* __TRANSLATION_IDL__ */
  226.  
  227.